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Advanced Batocera Configuration Syntax 


Most settings (including RetroArch-specific settings) can be adjusted from within the menus in 
EmulationStation. This includes per system and per game settings, access per system settings by 
pressing [SELECT] while in the system list and scrolling to ADVANCED SYSTEM SETTINGS and 


access per game settings by holding or while the game in question is selected (in Batocera v31 and 
lower, this is instead tapping <<”). 


However, there are a couple of (usually very recently implemented) settings that can only be set by 
manually editing files. This includes RetroArch's core-specific options which are not already available 
in the per system settings. 


batocera.conf option keys and values 


/userdata/system/batocera. conf is the main user-configuration file in Batocera, it can be 
accessed from the network share or the file manager or via SSH with the following: 


nano /userdata/system/batocera. conf 


This will contain all the settings you may have set in GAME SETTINGS, ADVANCED PER SYSTEM 
OPTIONS and a few other places. 


A surprising amount of configuration is handled by EmulationStation's internal system 
P (independent of Batocera), the configuration file of which can be found at 
/userdata/system/configs/emulationstation. 


batocera.conf uses the following syntax (objects in <> are required and have to be replaced, 
including the <> symbols themselves, objects in () are optional and objects separated by a pipe | 
indicate exclusive or): 
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(<system>([{["<ROM filename>.<ROM extension>"|.)|folder|"<path>"] .)<key 
name>(.<subkey 1 name> ...)=<value> 


which can be boiled down in its simplest form to: 
<option>=<value> 


Batocera option 


It can be a bit confusing seeing all the possibilities laid out like above so here's a simple example for a 
Batocera option: 


audio. bgmusic=0 

This will turn off the background music in the menu. Here, the key name is “audio”, the first subkey 
name is “bgmusic” and the value is “1”. No <system>, <ROM filename> or <ROM extension> is 
used. 

System-specific option 

Here's an example of changing a setting for every game of a specific system: 


nes. bezel=none 


This will turn off decorations for all games of the NES system. Here, the system is “nes”, the key 
name is “bezel” and the value is “none”. No <subkey # name>, <ROM filename> or <ROM 
extension> is used. 


Game-specific option 
Here's an example of changing a setting for a specific game of a system: 


c64/ "Arkanoid - Revenge of Doh (USA, Europe).zip"|.external palette=vice 


This will change the EXTERNAL PALETTE option for the Commodore 64 game “Arkanoid - Revenge 
of Doh” to use the “vice” palette. Here, the system is “c64”, the ROM filename and extension is 
“Arkanoid - Revenge of Doh (USA, Europe).zip”, the key name is “external_palette” and the value is 
“vice”. No <subkey # name> is used. 


Folder-specific option (introduced in v34) 


Here's an example of setting an option for games launched from a certain folder: 


nes.folder["/userdata/roms/nes/Japan/" | .shaderset=Mega-Bezel -Community -JP- 
Night 


This will set the shader set used for all NES games in the /userdata/roms/nes/Japan folder to use 
the night variant of the Famicom decoration (Mega-Bezel-Community-JP-Night). 


A Game-specific and folder-specific setting syntaxes conflict with one another. A key using 
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D both at the same time will be invalid and ignored. 


Key names, systems and values are not locale-specific, they will be the same regardless of which 
language you are using. The option names themselves are only translated on ES itself when in the 
menu, the internal key names stay the same. 


The absence of a key/value will imply its default "AUTO" setting will be used. In fact, this is the only 
way to use the “AUTO” setting. 


Comments 


Comments are treated a bit special with batocera. conf. A general comment that exists to explain 
what an option might do (a few of these are already included by default) is indicated by two hash 
symbols opening the line. For example: 


## Set the audio device 


which will simply be completely ignored by Batocera. 


Then there are special “disable setting” comments, which are indicated by a single hash opening the 
line. For example: 


#wifi.key=new key 


These settings, which still commented out, will be ignored by Batocera. However, if using "batocera- 
settings-get" or "batocera-settings-set" from SSH, error code 11 will be returned (“Value error, key 
found but it is commented out”). In order to fix this, either manually remove the comment from the 
setting or activate the key entry by using the uncomment command. 


How do I find out what available keys I can use are? 


If you'd like to see what the internal names of the options are, the quickest way is to set the setting in 
ES itself and exiting out of the menu to refresh batocera. conf, seeing what new line was added to 
batocera.conf. 


However, if you'd like to find the keys manually, you have to change your approach depending on 
which keys you are after: 


e To find the global keys (ones that can be applied to most systems) manually, look through the 
code and figure out its logic in the launcher script (in the /usr/lLib/python#.#/site- 
packages/configgen/ folder). 


e To find the emulator keys (of which apply to all systems that emulator supports, usually) 
manually, look through the code and figure out its logic in its configuration generator (most of 
which are in /usr/Lib/python#.#/site-packages/configgen/generators/). 


e To see system-specific keys, look at the 
/usr/share/emulationstation/es features.cfg file. The features tag shows which 
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“global” keys can be applied to your system, while the rest of the system-specific keys are 
specified in their own core option section. 


Although option names that appear in the menu may change from time to time, the 

internal option names tend to be resilient to change. This is done to ensure that 

batocera. conf files created with newer versions will have the highest chance of being 

perfectly backward compatible with older versions of Batocera (with options introduced 
> with newer versions of Batocera simply being ignored). 


However, it is possible that the values of some options may be changed/amended, 
causing the “future” values to be treated as 'default' by versions of Batocera that don't 
support it. It is important to keep this in mind if you are using versions of Batocera that 
are very far apart. 


"AUTO" setting behavior 


As mentioned above, leaving a key absent will use its “AUTO” setting. But what is that, exactly? It's 
complicated, technically it could be anything depending on the platform, system, generator, etc. The 
understanding of Python and its PYAML syntax is required. 


When an option is on “AUTO”, first Batocera checks if there is any “default” value for the option in 
/usr/share/batocera/configgen/configgen-defaults.yml and apply them to the 
configuration. For example, this is how the “default” emulator is selected for each system. Then, it 
checks /usr/share/batocera/configgen/configgen-defaults-arch.yml for any platform- 
specific defaults that should be applied. For example, this is how the “default” emulator is changed on 
platforms that don't have the same amount of emulators available to them (like RPi 0 and such). 


When neither of the above files have a value for the key in question, the “AUTO” behavior is then 
dependent on configuration generator for that particular emulator. 


RetroArch-specific options 


RetroArch is a special exception, being as utilized as it is by Batocera it makes sense that it would 
have its own set of subkeys. 


First is the general RetroArch settings. Don't be fooled, not all of RetroArch's settings have been 
integrated into Batocera, as every key needs to be manually coded in to be respected. Batocera is 
mostly on the ball with this, but sometimes things will slip through/be unavailable for other reasons 
(like menu option visibility, as the wrong menu option could break Batocera). 


RetroArch settings are technically per-system settings, so the <system>[\["<ROM 
filename>.<ROM extension>"\]. part at the start is still required, but for most purposes 
global. can be used. 


The subkey name for RetroArch's settings is retroarch and the subkey after that is usually identical 
to RetroArch's key for the respective setting. Unlike RetroArch, no double quotes are required for the 
setting's value, however including them won't break anything. Here is the syntax: 
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<system>(["<ROM filename>.<ROM 
extension>"||folder{"<path>"|).retroarch.<RetroArch setting name>=<value> 


which can be boiled down to (if desiring to apply it to all systems): 
<system>.retroarch.<RetroArch setting name>=<value> 
For example: 


global. retroarch.video hard sync=true 


saturn.retroarch.video hard sync=true 


A list of the currently known RetroArch settings and more details about their purpose can be found on 
its respective page. 


RetroArch core-specific options 


In addition to RetroArch's general settings, each libretro core has its own set of settings that can be 
configured as well. Unlike with RetroArch general settings, here any core setting can be set irrelevant 
of whether Batocera knows about it yet or not. The syntax is as follows: 


<system>(["<ROM filename>.<ROM extension>"].)retroarchcore.<core 
option>=<value> 


which can be boiled down to: 
<system>.retroarchcore.<core option>=<value> 
For example: 


global. retroarchcore.vice external palette=vice 


c64.retroarchcore.vice external palette=vice 
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Outside of the core developer providing it themselves, there is no documentation on 
what internal names the core options use. Probably because the end-user should never 
es have to be editing them like this in the first place. 


You can manually deduced these options yourself by following the instructions on the 
Advanced RetroArch settings page. 


/userdata/system/configs/emulationstation 


2 To do: EmulationStation's advanced configuration. 
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